3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Manipulating Rotate-About-Point Transforms

QuickDraw 3D provides routines that you can use to create and manipulate rotate transforms about a point. A rotate-about-point transform rotates an object about the x , y , or z axis by a specified number of radians at an arbitrary point in space. You can use macros to convert radians to degrees if you prefer to work with degrees instead of radians. See the chapter "Mathematical Utilities" for more information.

Q3RotateAboutPointTransform_New

You can use the Q3RotateAboutPointTransform_New function to create a new rotate-about-point transform.



 
TQ3TransformObject Q3RotateAboutPointTransform_New (

                     const TQ3RotateAboutPointTransformData *data);

data: A pointer to a TQ3RotateAboutPointTransformData structure.

DESCRIPTION

The Q3RotateAboutPointTransform_New function returns, as its function result, a reference to a new transform object of type kQ3TransformTypeRotateAboutPoint using the data passed in the data parameter. The data you pass is copied into internal QuickDraw 3D data structures. If QuickDraw 3D cannot allocate memory for those structures, Q3RotateAboutPointTransform_New returns the value NULL .

Q3RotateAboutPointTransform_Submit

You can use the Q3RotateAboutPointTransform_Submit function to submit a rotate-about-point transform without creating an object or allocating memory.



 
TQ3Status Q3RotateAboutPointTransform_Submit (

                     const TQ3RotateAboutPointTransformData *data, 

                     TQ3ViewObject view);

data: A pointer to a TQ3RotateAboutPointTransformData structure.
view: A view.

DESCRIPTION

The Q3RotateAboutPointTransform_Submit function pushes the rotate-about-point transform specified by the data parameter onto the view transform stack of the view specified by the view parameter. The function returns kQ3Success if the operation succeeds and kQ3Failure otherwise.

SPECIAL CONSIDERATIONS

You should call this function only in a submitting loop.

Q3RotateAboutPointTransform_GetData

You can use the Q3RotateAboutPointTransform_GetData function to query the private data stored in a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_GetData (

                     TQ3TransformObject transform, 

                     TQ3RotateAboutPointTransformData *data);

transform: A transform.
data: A pointer to a rotate-about-point data structure.

DESCRIPTION

The Q3RotateAboutPointTransform_GetData function returns, in the data parameter, information about the rotate-about-point transform specified by the transform parameter. You should use Q3RotateAboutPointTransform_GetData only with transforms of type kQ3TransformTypeRotateAboutPoint .

Q3RotateAboutPointTransform_SetData

You can use the Q3RotateAboutPointTransform_SetData function to set new private data for a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_SetData (

                     TQ3TransformObject transform, 

                     const TQ3RotateAboutPointTransformData *data);

transform: A transform.
data: A pointer to a rotate-about-point data structure.

DESCRIPTION

The Q3RotateAboutPointTransform_SetData function sets the rotate-about-point transform specified by the transform parameter to the data passed in the data parameter. You should use Q3RotateAboutPointTransform_SetData only with transforms of type kQ3TransformTypeRotateAboutPoint .

Q3RotateAboutPointTransform_GetAxis

You can use the Q3RotateAboutPointTransform_GetAxis function to get the axis of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_GetAxis (

                     TQ3TransformObject transform, 

                     TQ3Axis *axis);

transform: A rotate-about-point transform.
axis: On exit, the axis of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_GetAxis function returns, in the axis parameter, the current axis of rotation of the rotate-about-point transform specified by the transform parameter.

Q3RotateAboutPointTransform_SetAxis

You can use the Q3RotateAboutPointTransform_SetAxis function to set the axis of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_SetAxis (

                     TQ3TransformObject transform, 

                     TQ3Axis axis);

transform: A rotate-about-point transform.
axis: The desired axis of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_SetAxis function sets the axis of rotation for the rotate-about-point transform specified by the transform parameter to the value passed in the axis parameter.

Q3RotateAboutPointTransform_GetAngle

You can use the Q3RotateAboutPointTransform_GetAngle function to get the angle of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_GetAngle (

                     TQ3TransformObject transform, 

                     float *radians);

transform: A rotate-about-point transform.
radians: On exit, the angle, in radians, of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_GetAngle function returns, in the radians parameter, the current angle of rotation (in radians) of the rotate-about-point transform specified by the transform parameter.

Q3RotateAboutPointTransform_SetAngle

You can use the Q3RotateAboutPointTransform_SetAngle function to set the angle of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_SetAngle (

                     TQ3TransformObject transform, 

                     float radians);

transform: A rotate-about-point transform.
radians: The desired angle, in radians, of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_SetAngle function sets the angle of rotation for the rotate-about-point transform specified by the transform parameter to the value passed in the radians parameter.

Q3RotateAboutPointTransform_GetAboutPoint

You can use the Q3RotateAboutPointTransform_GetAboutPoint function to get the point of rotation of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_GetAboutPoint (

                     TQ3TransformObject transform, 

                     TQ3Point3D *about);

transform: A rotate-about-point transform.
about: On exit, the point of rotation of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_GetAboutPoint function returns, in the about parameter, the current point of rotation of the rotate-about-point transform specified by the transform parameter.

Q3RotateAboutPointTransform_SetAboutPoint

You can use the Q3RotateAboutPointTransform_SetAboutPoint function to set the point of rotation of a rotate-about-point transform.



 
TQ3Status Q3RotateAboutPointTransform_SetAboutPoint (

                     TQ3TransformObject transform, 

                     const TQ3Point3D *about);

transform: A rotate-about-point transform.
about: The desired point of rotation of the specified rotate-about-point transform.

DESCRIPTION

The Q3RotateAboutPointTransform_SetAboutPoint function sets the point of rotation for the rotate-about-point transform specified by the transform parameter to the value passed in the about parameter.